home *** CD-ROM | disk | FTP | other *** search
/ Miggybyte 10 / Miggybyte 10.adf / DOCS / MMMC_30.TXT / MMMC_30.TXT
Text File  |  2022-11-05  |  10KB  |  292 lines
  1. --------------------------------------------------------------------------------
  2.                                    XRef 1.1
  3.                                 Andreas Mixich
  4. --------------------------------------------------------------------------------
  5.  
  6. BRIEF DESCRIPTION
  7.  
  8.         Package of a shared library, ARexx function-library and utils
  9. to generate and handle binary xref files on AutoDocs, Includes, UNIX
  10. man pages and AmigaGuides.
  11.  
  12.  
  13.  
  14. AUTHOR/COMPANY INFORMATION
  15.  
  16.         Address:        Stefan Ruppert
  17.                         Windthorststrasse 5
  18.                         65439 Floersheim am Main
  19.                         GERMANY
  20.  
  21.         E-mail:         ruppert@vs3.informatik.fh-wiesbaden.de
  22.                         ruppert@goofy.zdv.uni-mainz.de
  23.         WWW:            http://www.uni-mainz.de/~ruppert/amiga/amiga.html
  24.  
  25.  
  26. LIST PRICE
  27.  
  28.         DM 20 or US$ 15
  29.  
  30.  
  31. DEMO VERSION
  32.  
  33.         Identical with full release.
  34.  
  35.  
  36. SPECIAL HARDWARE AND SOFTWARE REQUIREMENTS
  37.  
  38.  
  39.         HARDWARE
  40.  
  41.                 Some harddisk space for installation and to store
  42.                 converted docs is required
  43.  
  44.         SOFTWARE
  45.  
  46.                 AmigaGuide installation
  47.                 AmigaDOS 2.x
  48.  
  49.  
  50. COPY PROTECTION
  51.  
  52.         None
  53.  
  54.         HD installation possible, installer script included.
  55.  
  56.  
  57. MACHINE USED FOR TESTING
  58.  
  59.  
  60.         Amiga 1200, Blizzard 1220 (68020/28), 68882 FPU, 8MB Fast Ram,
  61.         540 MB HD
  62.         AmigaOS 3.0
  63.  
  64.         Amiga 4000, CyberStorm060/CyberSCSI,
  65.         CyberVision/4
  66.         16MB Fast Ram
  67.         NEC 4x CD-ROM
  68.         MFC III
  69.         2x Floppy
  70.         Kickstart 40.70, Workbench 40.42
  71.  
  72.         On both machines, several well known patches were installed.
  73.  
  74.  
  75.  
  76. INSTALLATION
  77.  
  78.         Installation is comfortably done by Commodore's Installer.
  79.         A second installer scriot exists, to create a basic conversion
  80.         of all system-Includes&AutoDocs.
  81.  
  82.  
  83. INTRO
  84.  
  85.         Are you a programmer ? Do you like to hit a key in your editor to
  86.         look up a functions' AutoDoc page ? Do you fear the next time of
  87.         preparation and conversion of some new AutoDocs with ADoc2XRef ?
  88.         Or maybe want to convert Includes as well or, include your UNIX man
  89.         pages in your Amiga-hypertext documentation ?
  90.  
  91.         Do you want to have a search capability for XRef entries in your
  92.         AmigaGuide reader ?
  93.  
  94.         Or maybe you want to program a new application, that shall have XRef
  95.         capabilities ?
  96.  
  97.         Or you want to have a standard on your Amiga to access docs in an
  98.         easy way ?
  99.  
  100.         Here is the solution: XRef 1.1 by Stefan Ruppert, who also wrote
  101.         some well known datatypes as the C-,CLI-,MAN.datatype,
  102.         the HTDS dataypes system, DTPatch and MultiPrint.
  103.  
  104.  
  105. FEATURES
  106.  
  107.         It will allow you to automatically create binary XRef files of
  108.         all previously mentioned document types. These XRef files are
  109.         handled by a shared library, which comes well documented and
  110.         with all the needed developer stuff. The library offers
  111.         functions for pattern-matching handling of these XRef files,
  112.         creation of 'dynamic nodes' for the AmigaGuide system and
  113.         more. Several tools exist, that may do all you could imagine
  114.         with the XRef files, like loading them, locking (Avail Flush
  115.         won't remove them from memory then), print out statistics,
  116.         general information. The most important tools are the ones you
  117.         need to generate the XRef files and convert the documents to
  118.         AmigaGuide format.  Another tool allows to generate an
  119.         AmigaGuide INDEX of one or many AmigaGuide documents at once.
  120.  
  121.         The whole system is blazingly fast when compared to the old way in
  122.         using ADoc2Guide. XRef generation and conversion of all OS3.1
  123.         Includes & Autodocs took about 45 minutes on the accelerated A1200,
  124.         as listed above. Note, that this includes time for loading,
  125.         scanning, xref-creation, conversion to Amigaguide and writing back
  126.         to disk. You may get some speed-up if you put the "raw" documents
  127.         into a Ram Disk.
  128.  
  129.         For the text editor 'GoldED V3' there is also an API available, that
  130.         allows phrase-completion from within the XRef files.
  131.  
  132.         Preferences allow to except several expressions and words from
  133.         being processed when generating XRef files or converting docs
  134.         to guides.
  135.  
  136.         There is also an AmigaGuide-like reader, that will display the
  137.         documents and features some search-gadgets. There exist
  138.         versions customized for V37 and V39 of the operating system.
  139.  
  140.         An ARexx macro is delivered for looking up the word under the
  141.         cursor within GoldED V3, but may be adapted easily to any
  142.         other editor.
  143.  
  144.  
  145.  
  146. INSTALLATION
  147.  
  148.         It's easy! The Installer script does everything for you.  A
  149.         second Installer script is delievered to create a basic
  150.         conversion of all System Includes&Autodocs.
  151.  
  152.  
  153. SOURCE
  154.  
  155.         The SAS/C sourcecode is available for all tools, except the
  156.         libraries.
  157.  
  158.  
  159. USAGE
  160.  
  161.         There are a lot ways to use this nice package. The basic use, of
  162.         course, is hunting for functions, macros or defines in the system's
  163.         documentation. Thanks to the ARexx version of the library this is
  164.         done very easy.
  165.  
  166.         Another way to use it is invocation of the special AmigaGuide reader by
  167.         submitting a pattern. All found occurences will be listed in a dynamic
  168.         node and are ready for selection.
  169.  
  170.         Given the fact, that this is a shared library one might imagine a lot
  171.         of other functionality:  Writing a text reader, that includes XRef
  172.         support, writing some AmigaGuide authoring tool, that uses the XRefs to
  173.         generate global links, 'Man'-type programs that not only display
  174.         documents, but also hunt for specified patterns and a lot more.
  175.  
  176.         Don't forget, that you can scan existing AmigaGuides and create
  177.         XRefs for them. So you are not only forced to ADoc&Inc type docs.
  178.  
  179. PERSONAL EXPERIENCES
  180.  
  181.         As soon as I got XRef1.1 I converted all my system's Includes &
  182.         Autodocs and a bit later the ones supplied with 3rd party
  183.         distributions, such as MUI or else. Some of the MUI AutoDocs cause
  184.         probles, but this is due to the fact, that these are not always
  185.         conforimg the standard.
  186.  
  187.         Additionally I have created XRef files which store all my ARexx docs'
  188.         links (ARexxGuide V2, RexxReqTools.guide and so on) and the SAS/C
  189.         online help. It might be interesting to create xrefs for the RKM
  190.         Amigaguide Edition, as available on the CATS V2 CD. Although, I have
  191.         no experiences with that.
  192.  
  193.         One might simply use it for scanning the AmigaE or any other well
  194.         structured guide, too.
  195.  
  196.         I was astonished ! With the aid of this system I was now finally able
  197.         to generate a documentary on my system, which I can access globally,
  198.         have a better overview and much more easy access.
  199.  
  200.         Also I could wirte a MAN command, that not only would display
  201.         documents, but search for certain strings in all docs and display found
  202.         occurances.
  203.  
  204.  
  205. FAZIT
  206.  
  207.         All in all I must say, that this is a tool I have been waiting for a
  208.         long time and am glad to have it. I believe this will make every
  209.         programming environment a "Dream Development System" since it offers
  210.         quick access to all available functions etc. by a simple keystroke.
  211.         The big speed over ADoc2Guide, the fact of automatically generated XRef
  212.         files, and the implementation as library make it unique.
  213.  
  214.         It is on Aminet for over a year now (dev/misc/xref_v1_1.lha), but
  215.         seems to be mainly unnoticed. This is the reason I wanted to give it
  216.         credit. It comes in the status of ShareWare but is uncrippled, no
  217.         functionality is lacking. The fee is an affordable DM 20 or US$ 15.
  218.  
  219.  
  220. DOCUMENTATION
  221.  
  222.         Documentation is complete. The library comes with includes and
  223.         an AutoDoc.  The tools are documented seperatly, each tool has
  224.         its own doc.  Some additional developer support, that was used
  225.         during creation of this package is included as well
  226.         (FinalReadArgs())
  227.  
  228.         For an advanced Amiga user (programmer) there should be
  229.         nothing lacking.
  230.  
  231. LIKES
  232.  
  233.         Well, not much to add. It is really a nice peace of software and
  234.         I would be glad to see this kind of implementation on any upcoming
  235.         Amiga operating system implemented from the very beginning.
  236.  
  237.  
  238. DISLIKES AND SUGGESTIONS
  239.  
  240.         No dislikes. I would be glad to see further development being done,
  241.         and the ARexx library expanded. 
  242.  
  243.  
  244. COMPARISON TO OTHER SIMILAR PRODUCTS
  245.  
  246.         ADoc2Guide does a similar task, but is, in opposite to XRef1.1 very
  247.         limited.
  248.  
  249.  
  250. BUGS
  251.  
  252.         Since AmigaGuide seems to have some problems with paths, it is
  253.         ecommended to add the PATH/K option when generating XRef files and to
  254.         include the paths, where the converted documents are stored in the
  255.         $AMIGAGUIDE/PATH variable. Then all should be perfect. You should
  256.         also edit the second Installer-script not to use an AG: assign.
  257.         Running a resident MultiView will cause problems, but this is a bug
  258.         in MultiView's path handling, I believe.
  259.  
  260.         The ARexx library returns RC_WARN (RC=5) if no entries were
  261.         found, which is interpreted by ARexx as 'Unmatched Quote'.
  262.  
  263.  
  264. VENDOR SUPPORT
  265.  
  266.         I have contacted Stefan several times with suggestions and ideas.
  267.         He was very kind and helpfull.
  268.  
  269.  
  270. WARRANTY
  271.  
  272.         I guess the standard disclaimer for software belongs here....
  273.  
  274.  
  275. CONCLUSIONS
  276.  
  277.         Product   is   very  good  and  a  brilliant  add-on  in  any  developer
  278. environment.  I would say:  It's a must-have !
  279.  
  280.         4 stars out of 5
  281.  
  282.  
  283.  
  284. COPYRIGHT NOTICE
  285.  
  286.  
  287.         Copyright 1996 Andreas Mixich
  288.         humpty@tomate.tng.oche.de
  289.  
  290. END
  291. ===
  292.